home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / man3 / WindowId.3 < prev   
Text File  |  1994-09-20  |  10KB  |  359 lines
  1. '\"
  2. '\" Copyright (c) 1990-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/WindowId.3,v 1.9 93/04/01 09:42:00 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_WindowId tkc
  206. .BS
  207. .SH NAME
  208. Tk_WindowId, Tk_Parent, Tk_Display, Tk_DisplayName, Tk_ScreenNumber, Tk_Screen, Tk_X, Tk_Y, Tk_Width, Tk_Height, Tk_Changes, Tk_Attributes, Tk_IsMapped, Tk_IsTopLevel, Tk_ReqWidth, Tk_ReqHeight, Tk_InternalBorderWidth, Tk_Visual, Tk_Depth, Tk_Colormap  \- retrieve information from Tk's local data structure
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tk.h>\fR
  212. .sp
  213. Window
  214. \fBTk_WindowId\fR(\fItkwin\fR)
  215. .sp
  216. Tk_Window
  217. \fBTk_Parent\fR(\fItkwin\fR)
  218. .sp
  219. Display *
  220. \fBTk_Display\fR(\fItkwin\fR)
  221. .sp
  222. char *
  223. \fBTk_DisplayName\fR(\fItkwin\fR)
  224. .sp
  225. int
  226. \fBTk_ScreenNumber\fR(\fItkwin\fR)
  227. .sp
  228. Screen *
  229. \fBTk_Screen\fR(\fItkwin\fR)
  230. .sp
  231. int
  232. \fBTk_X\fR(\fItkwin\fR)
  233. .sp
  234. int
  235. \fBTk_Y\fR(\fItkwin\fR)
  236. .sp
  237. int
  238. \fBTk_Width\fR(\fItkwin\fR)
  239. .sp
  240. int
  241. \fBTk_Height\fR(\fItkwin\fR)
  242. .sp
  243. XWindowChanges *
  244. \fBTk_Changes\fR(\fItkwin\fR)
  245. .sp
  246. XSetWindowAttributes *
  247. \fBTk_Attributes\fR(\fItkwin\fR)
  248. .sp
  249. int
  250. \fBTk_IsMapped\fR(\fItkwin\fR)
  251. .sp
  252. .VS
  253. int
  254. \fBTk_IsTopLevel\fR(\fItkwin\fR)
  255. .VE
  256. .sp
  257. int
  258. \fBTk_ReqWidth\fR(\fItkwin\fR)
  259. .sp
  260. int
  261. .br
  262. \fBTk_ReqHeight\fR(\fItkwin\fR)
  263. .sp
  264. int
  265. .br
  266. \fBTk_InternalBorderWidth\fR(\fItkwin\fR)
  267. .sp
  268. .VS
  269. Visual *
  270. .br
  271. \fBTk_Visual\fR(\fItkwin\fR)
  272. .sp
  273. int
  274. .br
  275. \fBTk_Depth\fR(\fItkwin\fR)
  276. .sp
  277. Colormap
  278. .br
  279. \fBTk_Colormap\fR(\fItkwin\fR)
  280. .VE
  281. .SH ARGUMENTS
  282. .AS Tk_Window tkwin
  283. .AP Tk_Window tkwin in
  284. Token for window.
  285. .BE
  286.  
  287. .SH DESCRIPTION
  288. .PP
  289. \fBTk_WindowID\fR and the other names listed above are
  290. all macros that return fields from Tk's local data structure
  291. for \fItkwin\fR.  None of these macros requires any
  292. interaction with the server;  it is safe to assume that
  293. all are fast.
  294. .PP
  295. \fBTk_WindowId\fR returns the X identifier for \fItkwin\fR,
  296. or \fBNULL\fR if no X window has been created for \fItkwin\fR
  297. yet (see the \fBTk_CreateMainWindow\fR manual entry for details).
  298. .PP
  299. \fBTk_Parent\fR returns Tk's token for the logical parent of
  300. \fItkwin\fR.  The parent is the token that was specified when
  301. \fItkwin\fR was created, or NULL for main windows.
  302. .PP
  303. \fBTk_Display\fR returns a pointer to the Xlib display structure
  304. corresponding to \fItkwin\fR.  \fBTk_DisplayName\fR returns an
  305. ASCII string identifying \fItkwin\fR's display.  \fBTk_ScreenNumber\fR
  306. returns the index of \fItkwin\fR's screen among all the screens
  307. of \fItkwin\fR's display.  \fBTk_Screen\fR returns a pointer to
  308. the Xlib structure corresponding to \fItkwin\fR's screen.
  309. .PP
  310. \fBTk_X\fR, \fBTk_Y\fR, \fBTk_Width\fR, and \fBTk_Height\fR
  311. return information about \fItkwin's\fR location within its
  312. parent and its size.  The location information refers to the
  313. upper-left pixel in the window, or its border if there is one.
  314. The width and height information refers to the interior size
  315. of the window, not including any border.  \fBTk_Changes\fR
  316. returns a pointer to a structure containing all of the above
  317. information plus a few other fields.  \fBTk_Attributes\fR
  318. returns a pointer to an XSetWindowAttributes structure describing
  319. all of the attributes of the \fItkwin\fR's window, such as background
  320. pixmap, event mask, and so on (Tk keeps track of all this information
  321. as it is changed by the application).  Note: it is essential that
  322. applications use Tk procedures like \fBTk_ResizeWindow\fR instead
  323. of X procedures like \fBXResizeWindow\fR, so that Tk can keep its
  324. data structures up-to-date.
  325. .PP
  326. \fBTk_IsMapped\fR returns a non-zero value if \fItkwin\fR
  327. is mapped and zero if \fItkwin\fR isn't mapped.
  328. .PP
  329. .VS
  330. \fBTk_IsTopLevel\fR returns a non-zero value if \fItkwin\fR
  331. is a top-level window (its X parent is the root window of the
  332. screen) and zero if \fItkwin\fR isn't a top-level window.
  333. .VE
  334. .PP
  335. \fBTk_ReqWidth\fR and \fBTk_ReqHeight\fR return information about
  336. the window's requested size.  These values correspond to the last
  337. call to \fBTk_GeometryRequest\fR for \fItkwin\fR.
  338. .PP
  339. \fBTk_InternalBorderWidth\fR returns the width of internal border
  340. that has been requested for \fItkwin\fR, or 0 if no internal border
  341. was requested.  The return value is simply the last value passed
  342. to \fBTk_SetInternalBorder\fR for \fItkwin\fR.
  343. .PP
  344. .VS
  345. \fBTk_Visual\fR, \fBTk_Depth\fR, and \fBTk_Colormap\fR return
  346. information about the visual characteristics of a window.
  347. \fBTk_Visual\fR returns the visual type for
  348. the window, \fBTk_Depth\fR returns the number of bits per pixel,
  349. and \fBTk_Colormap\fR returns the current
  350. colormap for the window.  The visual characteristics are
  351. normally set from the defaults for the window's screen, but
  352. they may be overridden by calling \fBTk_SetWindowVisual\fR.
  353. .VE
  354.  
  355. .SH KEYWORDS
  356. attributes, colormap, depth, display, height, geometry manager,
  357. identifier, mapped, requested size, screen, top-level,
  358. visual, width, window, x, y
  359.